<html><!-- Created using the cpp_pretty_printer from the dlib C++ library.  See http://dlib.net for updates. --><head><title>dlib C++ Library - random_cropper_abstract.h</title></head><body bgcolor='white'><pre>
<font color='#009900'>// Copyright (C) 2016  Davis E. King (davis@dlib.net)
</font><font color='#009900'>// License: Boost Software License   See LICENSE.txt for the full license.
</font><font color='#0000FF'>#undef</font> DLIB_RaNDOM_CROPPER_ABSTRACT_H_
<font color='#0000FF'>#ifdef</font> DLIB_RaNDOM_CROPPER_ABSTRACT_H_

<font color='#0000FF'>#include</font> "<a style='text-decoration:none' href='../threads.h.html'>../threads.h</a>"
<font color='#0000FF'>#include</font> <font color='#5555FF'>&lt;</font>mutex<font color='#5555FF'>&gt;</font>
<font color='#0000FF'>#include</font> <font color='#5555FF'>&lt;</font>vector<font color='#5555FF'>&gt;</font>
<font color='#0000FF'>#include</font> "<a style='text-decoration:none' href='interpolation.h.html'>interpolation.h</a>"
<font color='#0000FF'>#include</font> "<a style='text-decoration:none' href='../image_processing/full_object_detection.h.html'>../image_processing/full_object_detection.h</a>"
<font color='#0000FF'>#include</font> "<a style='text-decoration:none' href='../rand.h.html'>../rand.h</a>"

<font color='#0000FF'>namespace</font> dlib
<b>{</b>
    <font color='#0000FF'>class</font> <b><a name='random_cropper'></a>random_cropper</b>
    <b>{</b>
        <font color='#009900'>/*!
            WHAT THIS OBJECT REPRESENTS
                This object is a tool for extracting random crops of objects from a set of
                images.  The crops are randomly jittered in scale, translation, and
                rotation but more or less centered on objects specified by mmod_rect
                objects (or other rectangle types with a compatible interface).

            THREAD SAFETY
                It is safe for multiple threads to make concurrent calls to this object's
                operator() methods.
        !*/</font>

    <font color='#0000FF'>public</font>:

        <b><a name='random_cropper'></a>random_cropper</b> <font face='Lucida Console'>(</font>
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            ensures
                - #get_chip_dims() == chip_dims(300,300)
                - #get_randomly_flip() == true
                - #get_max_rotation_degrees() == 30
                - #get_min_object_length_long_dim() == 70 
                - #get_min_object_length_short_dim() == 30
                - #get_max_object_size() == 0.7
                - #get_background_crops_fraction() == 0.5
                - #get_translate_amount() == 0.1
                - #get_min_object_coverage == 1.0
        !*/</font>

        <font color='#0000FF'><u>void</u></font> <b><a name='set_seed'></a>set_seed</b> <font face='Lucida Console'>(</font>
            time_t seed
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            ensures
                - Seeds the internal random number generator with the given seed.
        !*/</font>

        <font color='#0000FF'><u>double</u></font> <b><a name='get_translate_amount'></a>get_translate_amount</b> <font face='Lucida Console'>(</font>
        <font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>; 
        <font color='#009900'>/*!
            ensures
                - When a box is cropped out, it will be randomly translated prior to
                  cropping by #get_translate_amount()*(the box's height) up or down and
                  #get_translate_amount()*(the box's width) left or right.
        !*/</font>

        <font color='#0000FF'><u>void</u></font> <b><a name='set_translate_amount'></a>set_translate_amount</b> <font face='Lucida Console'>(</font>
            <font color='#0000FF'><u>double</u></font> value
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            requires
                - value &gt;= 0
            ensures
                - #get_translate_amount() == value
        !*/</font>

        <font color='#0000FF'><u>double</u></font> <b><a name='get_background_crops_fraction'></a>get_background_crops_fraction</b> <font face='Lucida Console'>(</font>
        <font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>; 
        <font color='#009900'>/*!
            ensures
                - When making random crops, get_background_crops_fraction() fraction of
                  them will be from random background rather than being centered on some
                  object in the dataset.
        !*/</font>

        <font color='#0000FF'><u>void</u></font> <b><a name='set_background_crops_fraction'></a>set_background_crops_fraction</b> <font face='Lucida Console'>(</font>
            <font color='#0000FF'><u>double</u></font> value
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            requires
                - 0 &lt;= value &lt;= 1
            ensures
                - #get_background_crops_fraction() == value
        !*/</font>

        <font color='#0000FF'>const</font> chip_dims<font color='#5555FF'>&amp;</font> <b><a name='get_chip_dims'></a>get_chip_dims</b><font face='Lucida Console'>(</font>
        <font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>; 
        <font color='#009900'>/*!
            ensures
                - returns the dimensions of image chips produced by this object.
        !*/</font>

        <font color='#0000FF'><u>void</u></font> <b><a name='set_chip_dims'></a>set_chip_dims</b> <font face='Lucida Console'>(</font>
            <font color='#0000FF'>const</font> chip_dims<font color='#5555FF'>&amp;</font> dims
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            ensures
                - #get_chip_dims() == dims
        !*/</font>

        <font color='#0000FF'><u>void</u></font> <b><a name='set_chip_dims'></a>set_chip_dims</b> <font face='Lucida Console'>(</font>
            <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> rows,
            <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> cols
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            ensures
                - #get_chip_dims() == chip_dims(rows,cols)
        !*/</font>

        <font color='#0000FF'><u>bool</u></font> <b><a name='get_randomly_flip'></a>get_randomly_flip</b> <font face='Lucida Console'>(</font>
        <font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
        <font color='#009900'>/*!
            ensures
                - if this object will randomly mirror chips left to right.
        !*/</font>

        <font color='#0000FF'><u>void</u></font> <b><a name='set_randomly_flip'></a>set_randomly_flip</b> <font face='Lucida Console'>(</font>
            <font color='#0000FF'><u>bool</u></font> value
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            ensures
                - #get_randomly_flip() == value
        !*/</font>

        <font color='#0000FF'><u>double</u></font> <b><a name='get_max_rotation_degrees'></a>get_max_rotation_degrees</b> <font face='Lucida Console'>(</font>
        <font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
        <font color='#009900'>/*!
            ensures
                - When extracting an image chip, this object will pick a random rotation
                  in the range [-get_max_rotation_degrees(), get_max_rotation_degrees()]
                  and rotate the chip by that amount.
        !*/</font>

        <font color='#0000FF'><u>void</u></font> <b><a name='set_max_rotation_degrees'></a>set_max_rotation_degrees</b> <font face='Lucida Console'>(</font>
            <font color='#0000FF'><u>double</u></font> value
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            ensures
                - #get_max_rotation_degrees() == std::abs(value)
        !*/</font>

        <font color='#0000FF'><u>long</u></font> <b><a name='get_min_object_length_long_dim'></a>get_min_object_length_long_dim</b> <font face='Lucida Console'>(</font>
        <font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>; 
        <font color='#009900'>/*!
            ensures
                - When a chip is extracted around an object, the chip will be sized so that
                  the longest edge of the object (i.e. either its height or width,
                  whichever is longer) is at least #get_min_object_length_long_dim() pixels
                  in length.  When we say "object" here we are referring specifically to
                  the rectangle in the rectangle_type output by the cropper.
        !*/</font>

        <font color='#0000FF'><u>long</u></font> <b><a name='get_min_object_length_short_dim'></a>get_min_object_length_short_dim</b> <font face='Lucida Console'>(</font>
        <font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
        <font color='#009900'>/*!
            ensures
                - When a chip is extracted around an object, the chip will be sized so that
                  the shortest edge of the object (i.e. either its height or width,
                  whichever is shorter) is at least #get_min_object_length_short_dim()
                  pixels in length.  When we say "object" here we are referring
                  specifically to the rectangle in the rectangle_type output by the cropper.
        !*/</font>

        <font color='#0000FF'><u>void</u></font> <b><a name='set_min_object_size'></a>set_min_object_size</b> <font face='Lucida Console'>(</font>
            <font color='#0000FF'><u>long</u></font> long_dim,
            <font color='#0000FF'><u>long</u></font> short_dim
        <font face='Lucida Console'>)</font>; 
        <font color='#009900'>/*!
            requires
                - 0 &lt; short_dim &lt;= long_dim
            ensures
                - #get_min_object_length_short_dim() == short_dim
                - #get_min_object_length_long_dim() == long_dim
        !*/</font>

        <font color='#0000FF'><u>double</u></font> <b><a name='get_max_object_size'></a>get_max_object_size</b> <font face='Lucida Console'>(</font>
        <font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>; 
        <font color='#009900'>/*!
            ensures
                - When a chip is extracted around an object, the chip will be sized so that
                  both the object's height and width are at most get_max_object_size() *
                  the chip's height and width, respectively.  E.g. if the chip is 640x480
                  pixels in size then the object will be at most 480*get_max_object_size()
                  pixels tall and 640*get_max_object_size() pixels wide. 
        !*/</font>

        <font color='#0000FF'><u>void</u></font> <b><a name='set_max_object_size'></a>set_max_object_size</b> <font face='Lucida Console'>(</font>
            <font color='#0000FF'><u>double</u></font> value
        <font face='Lucida Console'>)</font>; 
        <font color='#009900'>/*!
            requires
                - 0 &lt; value 
            ensures
                - #get_max_object_size() == value
        !*/</font>

        <font color='#0000FF'><u>double</u></font> <b><a name='get_min_object_coverage'></a>get_min_object_coverage</b> <font face='Lucida Console'>(</font>
        <font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
        <font color='#009900'>/*!
            ensures
                - When a chip is extracted, any object that has less than get_min_object_coverage() fraction of its 
                   total area contained within the crop will have its ignore field set to true.
        !*/</font>

        <font color='#0000FF'><u>void</u></font> <b><a name='set_min_object_coverage'></a>set_min_object_coverage</b> <font face='Lucida Console'>(</font>
            <font color='#0000FF'><u>double</u></font> value
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            requires
                - 0 &lt; value &lt;= 1
            ensures
                - #get_min_object_coverage() == value
        !*/</font>

        <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
            <font color='#0000FF'>typename</font> array_type,
            <font color='#0000FF'>typename</font> rectangle_type
            <font color='#5555FF'>&gt;</font>
        <font color='#0000FF'><u>void</u></font> <b><a name='append'></a>append</b> <font face='Lucida Console'>(</font>
            <font color='#0000FF'><u>size_t</u></font> num_crops,
            <font color='#0000FF'>const</font> array_type<font color='#5555FF'>&amp;</font> images,
            <font color='#0000FF'>const</font> std::vector<font color='#5555FF'>&lt;</font>std::vector<font color='#5555FF'>&lt;</font>rectangle_type<font color='#5555FF'>&gt;</font><font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> rects,
            array_type<font color='#5555FF'>&amp;</font> crops,
            std::vector<font color='#5555FF'>&lt;</font>std::vector<font color='#5555FF'>&lt;</font>rectangle_type<font color='#5555FF'>&gt;</font><font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> crop_rects
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            requires
                - images.size() == rects.size()
                - crops.size() == crop_rects.size()
                - for all valid i:
                    - images[i].size() != 0
                - array_type is a type with an interface compatible with dlib::array or
                  std::vector and it must in turn contain image objects that implement the
                  interface defined in dlib/image_processing/generic_image.h 
                - rectangle_type is a type with an interface compatible with mmod_rect, such
                  as yolo_rect.
            ensures
                - Randomly extracts num_crops chips from images and appends them to the end
                  of crops.  We also copy the object metadata for each extracted crop and
                  store it into #crop_rects.  In particular, calling this function is the
                  same as making multiple calls to the version of operator() below that
                  outputs a single crop, except that append() will use multiple CPU cores
                  to do the processing and is therefore faster.
                - #crops.size() == crops.size()+num_crops
                - #crop_rects.size() == crop_rects.size()+num_crops
        !*/</font>

        <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
            <font color='#0000FF'>typename</font> array_type,
            <font color='#0000FF'>typename</font> rectangle_type
            <font color='#5555FF'>&gt;</font>
        <font color='#0000FF'><u>void</u></font> <b><a name='operator'></a>operator</b><font face='Lucida Console'>(</font><font face='Lucida Console'>)</font> <font face='Lucida Console'>(</font>
            <font color='#0000FF'><u>size_t</u></font> num_crops,
            <font color='#0000FF'>const</font> array_type<font color='#5555FF'>&amp;</font> images,
            <font color='#0000FF'>const</font> std::vector<font color='#5555FF'>&lt;</font>std::vector<font color='#5555FF'>&lt;</font>rectangle_type<font color='#5555FF'>&gt;</font><font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> rects,
            array_type<font color='#5555FF'>&amp;</font> crops,
            std::vector<font color='#5555FF'>&lt;</font>std::vector<font color='#5555FF'>&lt;</font>rectangle_type<font color='#5555FF'>&gt;</font><font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> crop_rects
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            requires
                - images.size() == rects.size()
                - for all valid i:
                    - images[i].size() != 0
                - array_type is a type with an interface compatible with dlib::array or
                  std::vector and it must in turn contain image objects that implement the
                  interface defined in dlib/image_processing/generic_image.h 
                - rectangle_type is a type with an interface compatible with mmod_rect, such
                  as yolo_rect.
            ensures
                - Randomly extracts num_crops chips from images.  We also copy the object
                  metadata for each extracted crop and store it into #crop_rects.  In
                  particular, calling this function is the same as invoking the version of
                  operator() below multiple times, except that this version of operator()
                  will use multiple CPU cores to do the processing and is therefore faster.
                - #crops.size() == num_crops
                - #crop_rects.size() == num_crops
        !*/</font>

        <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
            <font color='#0000FF'>typename</font> array_type,
            <font color='#0000FF'>typename</font> image_type,
            <font color='#0000FF'>typename</font> rectangle_type
            <font color='#5555FF'>&gt;</font>
        <font color='#0000FF'><u>void</u></font> <b><a name='operator'></a>operator</b><font face='Lucida Console'>(</font><font face='Lucida Console'>)</font> <font face='Lucida Console'>(</font>
            <font color='#0000FF'>const</font> array_type<font color='#5555FF'>&amp;</font> images,
            <font color='#0000FF'>const</font> std::vector<font color='#5555FF'>&lt;</font>std::vector<font color='#5555FF'>&lt;</font>rectangle_type<font color='#5555FF'>&gt;</font><font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> rects,
            image_type<font color='#5555FF'>&amp;</font> crop,
            std::vector<font color='#5555FF'>&lt;</font>rectangle_type<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> crop_rects
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            requires
                - images.size() == rects.size()
                - for all valid i:
                    - images[i].size() != 0
                - image_type == an image object that implements the interface defined in
                  dlib/image_processing/generic_image.h 
                - array_type is a type with an interface compatible with dlib::array or
                  std::vector and it must in turn contain image objects that implement the
                  interface defined in dlib/image_processing/generic_image.h 
                - rectangle_type is a type with an interface compatible with mmod_rect, such
                  as yolo_rect.
            ensures
                - Selects a random image and creates a random crop from it.  Specifically,
                  we pick a random index IDX &lt; images.size() and then execute 
                    (*this)(images[IDX],rects[IDX],crop,crop_rects) 
        !*/</font>

        <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
            <font color='#0000FF'>typename</font> image_type1,
            <font color='#0000FF'>typename</font> image_type2,
            <font color='#0000FF'>typename</font> rectangle_type
            <font color='#5555FF'>&gt;</font>
        <font color='#0000FF'><u>void</u></font> <b><a name='operator'></a>operator</b><font face='Lucida Console'>(</font><font face='Lucida Console'>)</font> <font face='Lucida Console'>(</font>
            <font color='#0000FF'>const</font> image_type1<font color='#5555FF'>&amp;</font> img,
            <font color='#0000FF'>const</font> std::vector<font color='#5555FF'>&lt;</font>rectangle_type<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> rects,
            image_type2<font color='#5555FF'>&amp;</font> crop,
            std::vector<font color='#5555FF'>&lt;</font>rectangle_type<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> crop_rects
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            requires
                - img.size() != 0
                - image_type1 == an image object that implements the interface defined in
                  dlib/image_processing/generic_image.h 
                - image_type2 == an image object that implements the interface defined in
                  dlib/image_processing/generic_image.h 
                - rectangle_type is a type with an interface compatible with mmod_rect, such
                  as yolo_rect.
            ensures
                - Extracts a random crop from img and copies over the rectangle_type objects
                  in rects to #crop_rects if they are contained inside the crop.  Moreover,
                  rectangles are marked as ignore if they aren't completely contained
                  inside the crop.
                - #crop_rects.size() &lt;= rects.size()
        !*/</font>

        <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
            <font color='#0000FF'>typename</font> image_type1
            <font color='#5555FF'>&gt;</font>
        image_type1 <b><a name='operator'></a>operator</b><font face='Lucida Console'>(</font><font face='Lucida Console'>)</font> <font face='Lucida Console'>(</font>
            <font color='#0000FF'>const</font> image_type1<font color='#5555FF'>&amp;</font> img
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            requires
                - img.size() != 0
                - image_type1 == an image object that implements the interface defined in
                  dlib/image_processing/generic_image.h 
            ensures
                - This function simply calls (*this)(img, junk1, crop, junk2) and returns
                  crop.  Therefore it is simply a convenience function for extracting a
                  random background patch.
        !*/</font>
    <b>}</b>;

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    std::ostream<font color='#5555FF'>&amp;</font> <b><a name='operator'></a>operator</b><font color='#5555FF'>&lt;</font><font color='#5555FF'>&lt;</font> <font face='Lucida Console'>(</font>
        std::ostream<font color='#5555FF'>&amp;</font> out,
        <font color='#0000FF'>const</font> random_cropper<font color='#5555FF'>&amp;</font> item
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        ensures
            - Prints the state of all the parameters of item to out.
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
<b>}</b>

<font color='#0000FF'>#endif</font> <font color='#009900'>// DLIB_RaNDOM_CROPPER_ABSTRACT_H_
</font>

</pre></body></html>